RSU 1.0 Remote Software Update for DOS--Documentation Copyright (c) 1992 Burkhard Daniel & Hans-Georg Michna Table of Contents Brief Command Overview Licensing and Support Introduction How RSU Works Installing RSU RSU Server Preparation Workstation Preparation The RSU Development Cycle Steps of the RSU Development Cycle Prepare an RSU Test Workstation Create and Test the New Module Protect Users From Your Tests Upload the New Module to the RSU Server Adapt the RSU Program Test the New RSU Program Activate the New RSU Program Control Files RSU Batch File RSU Program (RSU.PRG) Alphabetical List of Commands General Command Syntax Environment Variables DOS Commands Equal IniAddLine IniChangeLine IniCopyLine IniCopySection IniDeleteLine IniDeleteSection SyncDir RSU____C.DOC [14] 26.12.92 Brief Command Overview In the following text each group of syntax lines is followed by one or more example lines which are indented. RSU RSU.EXE f: cd \rsu rsu rsu.prg EQUAL EQUAL.COM f:\rsu\equal f:\rsu\version.txt c:\rsu\version.txt IniAddLine [
] = IniAddLine C:\WIN31\SYSTEM.INI 386Enh device=VPD.386 IniAddLine C:\WIN31\SYSTEM.INI 386Enh device=%NEW_DEVICE% (The second example above also shows how to insert an environment variable.) IniChangeLine [
] = IniChangeLine C:\WIN31\WIN.INI [windows] load=NWPOPUP.EXE IniChangeLine C:\WIN31\WIN.INI [mail] mailbox=%USER% (The second example above also shows how to insert an environment variable.) IniCopyLine [
] IniCopyLine F:\RSU\WSIMAGE\WIN31\WIN.INI C:\WIN31\WIN.INI [windows] load IniCopyLine F:\RSU\WSIMAGE\WIN31\WIN.INI C:\WIN31\WIN.INI [windows] load= IniCopySection [
] IniCopySection F:\RSU\WSIMAGE\WIN31\WIN.INI C:\WIN31\WIN.INI [HPPCL5A,LPT1:] IniDeleteLine [
] IniDeleteLine C:\WIN31\WIN.INI [mail] Polling IniDeleteLine C:\WIN31\WIN.INI [mail] Polling= IniDeleteSection [
] IniDeleteSection C:\WIN31\WIN.INI [Microsoft Word] SyncDir [/D] [{ /O | /C }] [/A] [/S] SyncDir F:\RSU\WSIMAGE\U C:\U /D /O /A /S SyncDir F:\RSU\WSIMAGE\DOS C:\DOS /O /A SyncDir switches: /D Delete files from the target directory if they don't exist in the source directory. /A Add files to the target directory if they are not there already. /O Overwrite files in the target directory if they also exist in the source directory but are different (have different size, date or time). This switch may not be used together with the /C switch. /C Conflict management. This switch may not be used together with the /O switch. If a file name exists in both source and target directories but with different size, date or time, then this is considered a conflict and both files are retained with different file names (see full documentation). Licensing and Support RSU including its EQUAL.COM, SYNCDIR.EXE and documentation files is Copyright 1992 Burkhard Daniel and Hans-Georg Michna. It is distributed under the Shareware concept. Its use on isolated PCs, for example to change settings in WIN.INI through batch files without the involvement of any network file server is free, even if the computer is connected to a network. As soon as RSU is used to copy files from a network file server to a user's local storage or to copy any parts of files of the Windows INI type from a network file server, however, its free use is restricted to a 30 day trial period. After that the shareware fee has to be paid through CompuServe's SWREG if the program is still used. The fee is US $50.00 for each group of up to 100 users. In other words, if the program is used for 1 to 100 users, the fee is US $50.00. If it is used for 101 to 200 users, the fee is US $100.00, for 201 to 300 users US $150.00 and so on. Future enhanced versions of RSU may be more expensive. The program contains no technical means to enforce payment other than noting the requirement on screen when RSU is started. To pay the fee log on to CompuServe and enter the command: GO SWREG. Search for the keyword RSU and register according to the choices you get on screen. The program may be freely distributed as long as the files stay together unaltered and packed in one file using an archiving program like PKZIP, LHA or similar. It is not allowed to add any other files other than minor additions that do not exceed the size of the original files. It is not allowed to distribute RSU as part of another program or package because we fear that this might look as if RSU may no longer require its shareware fee payment which it always does according to the rules outlined above. Through CompuServe Mail you can reach Hans-Georg Michna 74776,2361 if you have questions, remarks or proposals for future enhancements of RSU. You can also reach him through Internet mail: 74776.2361@compuserve.com Disclaimer: At the present state of software technology it is not possible to create error-free software. RSU may contain errors. Anybody using it should take precautions like creating safety backups in case a defect causes damage to any computer or data. The authors of RSU can under no circumstances be held responsible for any damage. Introduction RSU (Remote Software Update) is a program that updates the software on many individual workstation1 PCs connected to a file server. The file server, when equipped with RSU, becomes an RSU server. The RSU program does not run on the RSU server, however. It runs only on the workstations. The RSU server consists only of subdirectories and files on the file server. Sample RSU installation The fundamental idea is that all workstation configurations are stored on the RSU server. RSU then copies the appropriate modules to each workstation while retaining individual settings or individual software on the workstations. The file server used for RSU does not have to be the same file server that is used for normal work. It is necessary, of course, that users log in to the RSU server from time to time to get the topical remote software update. Since the file server does not usually run DOS a separate RSU test workstation is needed to develop and test the configurations. If testing on different hardware is needed then one RSU test workstation is needed for each hardware setup. RSU test workstations can be used for other work when they are not being used for RSU development. Their RSU related configuration has to be totally reset, however, before it is used for testing. RSU can ù copy predetermined files from the RSU server to the workstations, ù change the contents of subdirectories, even whole subdirectory trees, on the workstation PCs such that they become equal to their parents on the RSU server, by adding, deleting or overwriting files on the target PC, ù add, change, copy or delete certain sections or certain lines in INI files like WIN.INI and SYSTEM.INI, ù find out whether each workstation is already up to date and skip the updating process. How RSU Works Since the file server or any program running on any workstation has normally no access to any local disks the main RSU program has to run on each workstation to work its magic. The most convenient way to achieve this is to run it each time any user logs in to the RSU server.2 This can be achieved in different ways on different operating systems. On a Novell network, for example, a command can be called up after the system login script finishes, by using the Novell EXIT "" syntax or by calling it in the middle of the login script with the # syntax. See the manual of your network for details. RSU can be called from a DOS batch file. It has one command line parameter which is the path of the RSU program file. Example: f:\rsu\rsu.exe f:\rsu\rsu.prg RSU.EXE will execute the RSU program file. Files are typically copied from the RSU server to the local disk or modified on the local disk. Instead of the local disk the individual user storage space may also be on a file server. In this case each user's private storage should be mapped to a drive like U:, such that each user sees his private storage area when he refers to U:. Installing RSU RSU Server Preparation Each file server can be a RSU server. The basic method is to keep a mirror image of a workstation in a RSU server directory, for example in F:\RSU\WSIMAGE. There can be several such directories for several different configurations. The configurations have to be created and tested on test workstations, then copied to the RSU server. In addition the RSU server needs one other directory with read-only access for the RSU program files RSU.EXE, EQUAL.COM, SYNCDIR.EXE and the RSU program file (example: RSU.PRG, example of RSU read-only directory: F:\RSU). RSU does not handle the management of more than one workstation configuration, but this can easily achieved by creating small signal files on the different workstations which indicate the configuration type. The existence of any of these signal files can then be queried by a simple "if exist" command in a batch file. Another method is the BIOS scan which can be performed by a utility like PC Magazine's STRINGS or by a small Basic program, for example. Thus the BIOS version of the computer or, for example, of the display adapter can be determined automatically and the appropriate configuration installed without any manual intervention. Workstation Preparation Before installing RSU you have to make sure that all workstations connected to the RSU server have a valid minimal installation. The absolute minimum would be an installed DOS and the minimal network drivers to be able to connect to the server. It is recommended that you have an initial workstation setup procedure to erase all RSU related directories and files from a workstation and recreate the whole minimal setup from scratch. This could be done with a batch file like INSTALL.BAT on the RSU server. This will be very useful for users if they have somehow destroyed vital files on their workstation. They will then have a way to get up and running again if all else fails and no service person is available. It is also conceivable to use RSU to such an extent that each and every file on the workstation is covered by RSU. This would have the advantage that every workstation would recover from any loss or mutilation of files automatically when logging on to the RSU server. But this will often not be practicable for performance or other reasons. A general hint is to reduce use of local hard disks and user specific storage to a minimum such that lengthy file copying is not required. It is easier to add a file to the file server than to 100 local hard disks. The RSU Development Cycle Steps of the RSU Development Cycle The RSU development cycle is the process of developing a new configuration. Frequently this will just be a small change in an existing configuration, but it could also be an entirely new configuration for a new type of workstation, for example. Development proceeds in these steps: 1.Prepare a RSU test workstation by making it equivalent to the topical RSU update level. 2.Create and test a new configuration or modify the existing one on a test workstation. 3.Temporarily protect users from your RSU server changes. 4.Upload (copy) the new workstation configuration to the RSU server or modify the existing one on the RSU server. 5.If necessary, adapt the RSU program file (example: RSU.PRG). 6.Test the new RSU setup on a test workstation. 7.Activate the new setup, such that it gets installed on all target workstation PCs (undo step 3). In many cases this development cycle can be shortened by skipping certain actions if their effect is minimal or if the number of workstations is low enough such that some risk can be taken. The following sections describe these actions in detail. Prepare an RSU Test Workstation First you have to make sure that your RSU test workstation is equal to a topical workstation elsewhere in the network. If the test workstation has not been used for anything that might have altered the files and directories concerned then it can be used right away. If not, and whenever there are any doubts, the test workstation should be installed fresh from the RSU server. It is a good precaution to log in once after installation and obtain the latest changes from the RSU server to make sure they are included in the workstation image on the RSU server. The RSU update level information can be stored in any file for each workstation. You only have to edit this file or touch it such that the file date or time is changed to force an update. Start the RSU program, normally by logging in to the RSU server. The test workstation should automatically be updated to the topical update level. After the test workstation is up to the present standard you can now make the desired changes. Create and Test the New Module Now you can make the desired modification on the test machine only. Test thoroughly, since all your users who use that module will depend on your conscientiousness. Protect Users From Your Tests As soon as you touch the RSU server all users who happen to use the server will receive any modification. Therefore you have to make sure that this does not happen. There are several ways to protect users: 1.Deactivate the whole RSU server until you are done with all changes. One way is to rename the RSU program. Without it RSU will not be able to do anything. Another is to activate a jump over the RSU part of the controlling batch file. 2.Leave the RSU server running and create a second RSU server at least for the module you intend to work on. This is not quite so difficult as it sounds. It may be necessary for bigger changes that require some time to work out. 3.If you are making a very small change and you are absolutely sure that even a mistake can do no harm you may risk to work on the hot system. But be careful! Depending on the number of workstations and likelihood of a login you should be able to make the change within seconds. This might be viable if you just want to change a few files, for example. Again do not forget to change the date and time of the RSU update level file afterwards, so all users get a new update when they log in. Upload the New Module to the RSU Server After you have tested the new configuration thoroughly on your test machine you can now copy the modifications to the RSU server (for example to the F:\RSU\WSIMAGE directory and its subdirectories). It is useful to have a program that can detect the difference between files on two drives like the Norton Commander™ with its "Compare directories" command. In any case be sure to copy all changes from the test machine to the RSU server. Adapt the RSU Program Now change the RSU program (example: F:\RSU\RSU.PRG) if necessary. The modified RSU program should be able to copy all modifications from the RSU server area to any workstation PC. If you make changes to files by means of direct manipulation by the RSU program, for example with IniChangeLine, be sure to make those changes on the original files on the RSU server as well, such that users who do an install from scratch also get them immediately before they receive the next RSU update. Test the New RSU Program After the update is entirely in place but not yet activated you should test it before releasing it to all users. For this you either need a second test machine or you have to reset the first one to the previous configuration which is still standard for all other users. Then you have to make sure that the new update affects only the test machine but not yet all the other users. There are several ways to achieve this. The easiest is to modify the batch file which calls RSU.EXE such that only the testing user gets the update. Example: ... if not "%USER%"=="SUPERVISOR" goto NOT_YET rem Enter other batch commands here rem then call RSU: f: cd \RSU rsu.exe rsu.prg :NOT_YET ... This sample batch file fragment presumes that the network user name was written into the environment variable USER, for example with the Novell Netware login script command DOS SET USER="%USER_ID". Check whether the update is correct. You may have to test each configuration separately if there are several. Activate the New RSU Program Finally, after you have convinced yourself that the new update works correctly, you can release it to all users by removing any blocking commands you might have inserted. From that very moment all users who log on will receive the update. Control Files RSU Batch File RSU will probably be called from a batch file, though it might also be called from some network specific script like Novell's System or User Login Script. Assuming it is called from a batch file, an example might be this: rem RSU Batch File rem First find whether this user has already rem received the latest version: f:\rsu\equal c:\rsu\version.txt f:\rsu\version.txt if not errorlevel 1 goto NO_UPDATE rem Display of version message: echo off cls type f:\rsu\version.txt echo. pause echo. rem Now call RSU program: c: cd \ f: cd \rsu rsu.exe rsu.prg rem Finally make sure user gets new VERSION.TXT rem such that he doesn't get this particular update rem again the next time he logs on: copy f:\rsu\version.txt c:\rsu :NO_UPDATE RSU Program (RSU.PRG) The RSU program is the file which controls all RSU operations. It should reside on the RSU server, for example as F:\RSU\RSU.PRG. All users should have read-only access to it. This is an example of an RSU.PRG file: rem RSU.PRG file rem Modifications to WIN.INI: IniCopySection f:\rsu\wsimage\win31\win.ini c:\win31\win.ini [fonts] IniCopySection f:\rsu\wsimage\win31\win.ini c:\win31\win.ini [devices] IniDeleteSection c:\win31\win.ini [ObscureOldProgram] IniCopyLine f:\rsu\wsimage\win31\win.ini c:\win31\win.ini [windows] load IniDeleteLine c:\win31\win.ini [fonts] Swiss= IniChangeLine c:\win31\win.ini [mail] mailbox=%USER% rem Modifications to SYSTEM.INI: IniAddLine c:\win31\system.ini [display] svgamode=98 rem Synchronization of user files: f:\rsu\syncdir f:\rsu\wsimage\win31 c:\win31 /a f:\rsu\syncdir f:\rsu\wsimage\util c:\util /a /o /d /s rem End Of File Alphabetical List of Commands General Command Syntax All control files are text files in which each line is followed by a carriage return/line feed pair (13dec and 10dec). Spaces and tab characters in the beginning of any line are totally ignored. In effect it is as if those characters were removed before executing the RSU.PRG program. Lines beginning with "REM " are comments. Upper and lower case are functionally equivalent. However, the case is retained when information is forwarded into another file. Substitutions of environment variables (like %USER%) are done before the commands are executed. If the first word in any line is a valid RSU command then it is executed. If not the line is deemed to be a DOS command and is forwarded to the DOS command processor. Note, however, that not every DOS command can be used. For example, the DOS command SET has no effect because it is running under a secondary command processor that has no access to the primary environment. Environment Variables Environment variables can be inserted in any command with the syntax: %% Example: IniChangeLine C:\WIN31\WIN.INI [mail] mailbox=%USER% This example will take the name from the USER= entry in the environment and substitute it for %USER% before executing the IniChangeLine command. For example, if the environment contains an entry reading: USER=DANIEL then the command will be changed to: IniChangeLine C:\WIN31\WIN.INI [mail] mailbox=DANIEL which is useful for example to save users the separate logging in to Microsoftr Mail. Hint: Novell Netware 3.11 can place essential system information entries in the environment with the SET ="" syntax. Example: SET USER="%USER_ID" DOS Commands Any command found in an RSU program file that is not a valid RSU command is deemed to be a DOS command. A secondary command processor (COMMAND.COM) is loaded and the command forwarded to it and executed. There is no error checking and no logging with DOS commands, so be careful to test and use them properly. Equal This command is not a normal RSU command but a DOS utility program EQUAL.COM which determines whether two files are exactly equal in size, date and time. The following sample batch file illustrates its use, but normally only one command if errorlevel 1 ... is necessary to determine whether the two files are equal. Syntax: equal Sample: f:\rsu\equal c:\rsu\version.txt f:\rsu\version.txt if not errorlevel 1 goto NO_UPDATE Extended sample batch file: @echo off equal.com %1 %2 IF ERRORLEVEL 4 goto NO_MEMORY IF ERRORLEVEL 3 goto FILE_NOT_FOUND IF ERRORLEVEL 2 goto WRONG_PARAMETERS IF ERRORLEVEL 1 goto NOT_EQUAL IF ERRORLEVEL 0 goto EQUAL :NOT_EQUAL echo The files %1 and %2 are not equal. goto FINISH :WRONG_PARAMETERS echo Wrong parameters! Usage: EQUAL.BAT goto FINISH :FILE_NOT_FOUND echo Error: One of the two files could not be found. goto FINISH :NO_MEMORY echo Error: Not enough memory to execute EQUAL.COM. goto FINISH :EQUAL echo The files %1 and %2 are equal. :FINISH IniAddLine This command is used to add a line where several lines have the same variable name, like for example the device= lines in SYSTEM.INI. It appends one further line to the section. The only exception occurs if the exact line, variable name and text, exists in the file already. In this particular case the command has no effect. In other words, the command does not produce exact duplicates of whole lines like: device=VPD.386 device=VPD.386 Syntax: IniAddLine [
] = Example: IniAddLine C:\WIN31\SYSTEM.INI 386Enh device=VPD.386 Note: Version 1.00 of RSU has a shortcoming that leads to a line being rejected as already present if the line to be newly added is equal to part of the line which is already present. For example, if a line "device=VPD.386" is already present in the section then RSU will refuse to add the line "device=VPD.3". IniChangeLine This command changes the text after the equals sign (=) in a certain section and a certain line in an .INI file. If the section does not exist it is newly created and appended to the .INI file first. If the line does not exist it is newly created and appended at the end of the section. If several lines with the same variable name exist in the section then this command is probably not appropriate and should not be used since it would change only one of the lines. Syntax: IniChangeLine [
] = Example: IniChangeLine C:\WIN31\WIN.INI [windows] load=NWPOPUP.EXE Note that there is presently no command to change only part of a line. If something like this is desired one possible workaround is to use EDLIN in batch mode. IniCopyLine This command finds a certain line within a section in an .INI file and copies it into another .INI file. If a line with the same variable name to the left of the equals sign (=) already exists it is replaced with the new line. If several lines with the same variable name exist in the section then this command is probably not appropriate. It will work on the first occurrence of the variable. Syntax: IniCopyLine [
] Examples: IniCopyLine F:\RSU\WSIMAGE\WIN31\WIN.INI C:\WIN31\WIN.INI [windows] load IniCopyLine F:\RSU\WSIMAGE\WIN31\WIN.INI C:\WIN31\WIN.INI [windows] load= Both example lines do the same thing. Each one would search the file F:\RSU\WSIMAGE\WIN31\WIN.INI for the section [windows]. Within the section it would locate the line beginning with load= and copy it into the line with the same section and variable name in the file C:\WIN31\WIN.INI. IniCopySection Same but copies whole section. Syntax: IniCopySection [
] Example: IniCopySection F:\RSU\WSIMAGE\WIN31\WIN.INI C:\WIN31\WIN.INI [HPPCL5A,LPT1:] This example would copy the whole section [HPPCL5A,LPT1:] from F:\RSU\WSIMAGE\WIN31\WIN.INI to C:\WIN31\WIN.INI. If there was a section with that name before it will be overwritten and all information lost entirely. If the previous section contained more or other lines than the new those old lines will be lost. IniDeleteLine This command deletes a line in an .INI file. Syntax: IniDeleteLine [
] Examples: IniDeleteLine C:\WIN31\WIN.INI [mail] Polling IniDeleteLine C:\WIN31\WIN.INI [mail] Polling= This example will search C:\WIN31\WIN.INI for the section [mail] and in this section for the line beginning with Polling=. This line will be deleted from WIN.INI. IniDeleteSection Syntax: IniDeleteSection [
] Example: IniDeleteSection C:\WIN31\WIN.INI [Microsoft Word] Both example lines do the same thing. Each one will search C:\WIN31\WIN.INI for the section [Microsoft Word]. The entire section will be deleted from WIN.INI. SyncDir Makes the target directory equal to the source directory including all files, but excepting all files that have a read- only, hidden or system attribute. Note that this is not an internal RSU command. Instead this command is handled like a DOS command and the SYNCDIR.EXE utility is called. This may be changed in a future version of RSU. SyncDir handles all files regardless of their attributes. Attributes are copied with each file. The SyncDir command requires switches to control its operation. The following switches can be used, and at least one of them has to be used, otherwise SyncDir will not do anything: /D Delete files from the target directory if they don't exist in the source directory. /A Add files to the target directory if they are not there already. /O Overwrite files in the target directory if they also exist in the source directory but are different (have different size, date or time). This switch may not be used together with the /C switch. /C Conflict management. This switch may not be used together with the /O switch. If a file name exists in both source and target directories but with different size, date or time, then this is considered a conflict and the following actions are taken: 1. Both files are put into the target directory and the older one gets a new name like !SYNnnnn.xxx where nnnn is a number between 0001 and 9999 and xxx is the original extension of the file. 2. A line is appended to the file !SYN0000.TXT in the target directory containing the date, time and conflicting file information separated by semicolons (;), ready for import into a conflict database. One possible purpose of this function is to allow users with portable PCs to copy their network user directories home with them and later reconciliate their local user directories with those on the network if both can have changed. Warning: SyncDir will overwrite or erase files with any attributes in the target directory and, with the /S switch, any of its subdirectories, even if they are read-only, hidden or system files. Syntax: SyncDir [/D] [< /O | /C >] [/A] [/S] Examples: SyncDir F:\RSU\WSIMAGE\U C:\U /D /O /A /S SyncDir F:\RSU\WSIMAGE\DOS C:\DOS /O /A The first line would make the directory C:\U and all of its subdirectories exactly equal to the directory F:\RSU\WSIMAGE\U and all of its subdirectories. The second would overwrite any files in C:\DOS that are different from their namesakes in F:\RSU\WSIMAGE\DOS. It would also add files that are missing in C:\DOS, but it would not delete or otherwise touch any additional files the user may have added to his DOS directory. It would also not touch any subdirectories of C:\DOS. _______________________________ 1 The term "workstation" is used here for all user PC's connected to the network, using DOS, not for engineering workstations running Unix or the like. 2 Another method is to run it each time the workstation is started, from the AUTOEXEC.BAT file. Since users have few rights on the file server at that time it would be necessary to adjust those rights such that all users have reading rights to all RSU data without being logged in. This may or may not be possible on different network operating systems.